home *** CD-ROM | disk | FTP | other *** search
/ CD Classic 39 / CD CLASSIC #39 (1998).iso / EMPRESA / visio / Vistdstd / Install / Data.Z / VAO.H < prev    next >
C/C++ Source or Header  |  1997-11-11  |  32KB  |  764 lines
  1. /*    VAO.H - Visio 4.0 VSL Interface
  2.  *  Copyright (C) 1991-1997 Visio Corporation. All rights reserved.
  3.  *
  4.  *    This file contains definitions that define the interface between
  5.  *    Visio and VSLs. A VSL is a dynamic link library that implements
  6.  *    the protocol defined herein. A VSL implements one or more Add-ons.
  7.  *    Each Add-on has a name and implements some operation. An Add-on 
  8.  *    can be invoked from Visio in several ways, e.g. by selecting it from 
  9.  *    Visio's Run Add-ons dialog, or by associating it with the double 
  10.  *    click action of a shape in a Visio drawing.
  11.  *
  12.  *    A Visio Add-on can also be developed as an executable file instead of
  13.  *    in a VSL. In general the advantage of doing it as a VSL is that it will 
  14.  *    run faster and integrate with Visio slightly more seamlessly. The 
  15.  *    advantate of doing an Add-on as an exe is that VSLs can't be developed 
  16.  *    using certain nice development environments such as Visual Basic.
  17.  *
  18.  *    A VSL can be written in C or in C++. It can be built for WIN16 or
  19.  *    for WIN32. However Visio16 will only load WIN16 VSLs and Visio32 
  20.  *    will only load WIN32 VSLs. 
  21.  *
  22.  *    Implementations for the methods protyped herein can be found in vao.c.
  23.  *    The c-cpp directory shipped with Visio contains this vao.h file and
  24.  *    vao.c. It also contains the source files for a sample VSL written in 
  25.  *    C and a sample VSL written in C++. The source for these sample projects 
  26.  *    is portable to either WIN16 or WIN32, but there are separate .mak files
  27.  *    provided for building the WIN16 or WIN32 versions of the projects.
  28.  */
  29.  
  30. #if !defined(_VAO_H)
  31. #define _VAO_H
  32.  
  33. #ifndef _INC_WINDOWS
  34. #include <windows.h>
  35. #endif
  36.  
  37. #if !defined(RC_INVOKED)
  38.     // Structs passed between visio and vsl defined to have no padding.
  39.     #pragma pack(1)         
  40. #endif
  41.  
  42. #if defined(__cplusplus)
  43. extern "C" {
  44. #endif
  45.  
  46. #if !defined(LOADDS)
  47.     #if defined(_WIN32)
  48.         #define LOADDS
  49.     #else
  50.         #define LOADDS _loadds
  51.     #endif
  52. #endif
  53.  
  54. #if !defined(VAOU_PROC)
  55.     #define VAOU_PROC(type)    type LOADDS PASCAL FAR
  56. #endif
  57.  
  58. // Even though definitions in this interface are "C" definitions, we want
  59. // it to be possible to embed structures defined as part of the interface
  60. // within C++ objects. Since structs are really classes in C++, it is
  61. // required that C++ know whether the "this" of the struct is near or
  62. // far. Any struct defined as part of this interface that is declared
  63. // using VAO_EMBEDDABLE_STRUCT can be embedded within a FAR C++ instance
  64. // as well as being used as an ordinary C structure.
  65. //
  66. #if !defined(VAO_EMBEDDABLE_STRUCT)
  67.     #if defined(__cplusplus)
  68.         #define VAO_EMBEDDABLE_STRUCT typedef struct FAR
  69.     #else
  70.         #define VAO_EMBEDDABLE_STRUCT typedef struct
  71.     #endif
  72. #endif
  73.  
  74. // Version of the VSL inteface defined herein.
  75. #define VAO_IFMAJOR ((WORD)2)        // Major interface version number.
  76. #define VAO_IFMINOR ((WORD)3)        // Minor interface version number.
  77.  
  78. //---------------------------------------------------------------------------
  79. //
  80. //    EXPECTED ADD-ON LIBRARY ENTRY POINT
  81. //    -----------------------------------
  82. //
  83. //    An Add-on library is expected to have an exported entry point of type
  84. //    VAOFUNC whose name is LPVAOENTRYNAME. When Visio loads an Add-on library
  85. //    it determines the address of the library's entry point by calling
  86. //    GetProcAddress() on this name.
  87. //
  88. //---------------------------------------------------------------------------
  89.  
  90. #define LPVAOENTRYNAME ((LPSTR)"VisioLibMain")
  91.  
  92. typedef WORD VAORC, FAR* LPVAORC;    // Visio Add-on Return code.
  93. typedef WORD VAOMSG, FAR* LPVAOMSG; // Visio Add-on Message code.
  94.  
  95. #if defined(_WIN32)
  96.     #define VAOCB __cdecl
  97. #else
  98.     #define VAOCB LOADDS PASCAL FAR
  99. #endif
  100.  
  101. typedef VAORC (VAOCB VAOFUNC) (VAOMSG,WORD,LPVOID);
  102.  
  103. typedef VAOFUNC *LPVAOFUNC;
  104.  
  105.  
  106. // VAOV2LSTRUCT
  107. // This structure is passed by Visio to a VSL's VisioLibMain() as an argument
  108. // accompanying most messages. 
  109. //
  110. VAO_EMBEDDABLE_STRUCT
  111.     {
  112.     HINSTANCE    hVisInst;            // Handle to running Visio instance.
  113.     LPVAOFUNC    lpfunc;             // Call back address in Visio.
  114.     WORD        wSessID;            // Id of session 
  115.  
  116.     LPVOID        lpArgs;             // Pointer to session arguments.
  117.                                     // Currently always null.
  118.                                     
  119.     LPSTR        lpCmdLineArgs;        // Analog of "cmd line args" passed to
  120.                                     // an exe when it gets WinExec'd. 
  121.                                     // Recipient shouldn't assume this is
  122.                                     // non-null or depend on any particular
  123.                                     // string to be passed to it.
  124.  
  125.     } VAOV2LSTRUCT, FAR* LPVAOV2LSTRUCT;
  126.  
  127. #define VAO_INV_SESSID ((WORD)0xFFFF)
  128.  
  129.  
  130. // VAOREGSTRUCT
  131. // This structure describes an Add-on implemented by a VSL. When Visio sends
  132. // an V2LMSG_ENUMADDONS message to a VSL, the VSL responds by sending several
  133. // L2VMSG_REGADDON messages back to Visio. The VSL passes a pointer to a 
  134. // VAOREGSTRUCT along with each L2VMSG_REGADDON message.
  135. //
  136. // A VAOREGSTRUCT describes an Add-on to Visio. In particular, it specifies:
  137. //
  138. //    - The Add-on's ordinal. When Visio tells the library to run an Add-on
  139. //      it identifies which Add-on by specifying the Add-on's ordinal.
  140. //    - Several attributes of the Add-on.
  141. //    - The enabling policy the Add-on wants to use.
  142. //    - the name of the Add-on.
  143. //
  144.  
  145. // VAO_ORDINAL: Specifies an add-on's ordinal.
  146. //
  147. typedef WORD VAO_ORDINAL, FAR* LPVAO_ORDINAL;
  148.  
  149. #define VAO_INV_ORD (0)             // The ordinal no valid Add-on can have.
  150.                                     // We choose 0 for invalid id because
  151.                                     // resources having id's equal to
  152.                                     // to VAO_ORDINAL are quite likely and
  153.                                     // resid's of 0 aren't cool.
  154.  
  155.  
  156. // VAO_ATTS: Specifies an add-on's attributes in the form of a mask of
  157. // zero or more VAO_AOATTS_xxx values.
  158. //
  159. typedef WORD VAO_ATTS, FAR* LPVAO_ATTS;
  160.  
  161. #define VAO_AOATTS_ISACTION    0x0001    // Add-on performs actions.
  162. #define VAO_AOATTS_HASABOUT    0x0002    // Add-on supplies an about for itself
  163. #define VAO_AOATTS_HASHELP    0x0004    // Add-on supplies help about itself.
  164. #define VAO_AOATTS_WAITCRSR 0x0008    // Keep wait cursor up when Add-on runs.
  165. #define VAO_AOATTS_DONTSHOW 0x0010    // Don't show addon in menus/dialogs.
  166.  
  167.  
  168. // VAO_ENABMASK: Specifies an add-on's enabling policy. Value should be
  169. // VAO_ENABLEALWAYS, VAO_ENABLEDYNAMIC or VAO_NEEDSxxx+[VAO_ENABLEDYNAMIC].
  170. //
  171. typedef WORD VAO_ENABMASK, FAR* LPVAO_ENABMASK;
  172.  
  173. #define VAO_ENABLEALWAYS    0xFFFF    // Add-on is always enabled.
  174.  
  175. #define VAO_ENABLEDYNAMIC    0        // Visio should query Add-on using
  176.                                     // V2LMSG_ISAOENABLED when it wants to
  177.                                     // know if Add-on is enabled. Add-on
  178.                                     // should respond VAORC_L2V_ENABLED or 0.
  179.  
  180. #define VAO_ENABLEDYNAMICEX    0x8000    // If Add-on is still considered enabled
  181.                                     // after VAO_NEEDSxxx has been checked,
  182.                                     // Visio will send V2LMSG_ISAOENABLED
  183.                                     // to Add-on. Add-on should respond
  184.                                     // VAORC_L2V_ENABLED or 0.
  185.  
  186. // Semi-dynamic enabling masks. If an Add-on is registered with an enabling
  187. // mask of e.g. VAO_NEEDSDOC then Visio will consider Add-on enabled only
  188. // if state implied by mask is in effect (e.g. only if a document is open if
  189. // mask is VAO_NEEDSDOC). Visio won't query a semi-dynamically enabled Add-on
  190. // to see if it is enabled unless VAO_ENABLEDYNAMICEX also set. Bits are 
  191. // negative, e.g. consider this add-on disabled if there is no target doc. 
  192. // If none of negative condictions met, add-on will be considered enabled.
  193. //
  194. #define _VAO_ND             0x0001    // Add-on needs a document.
  195. #define _VAO_NW             0x0002    // Add-on needs a window.
  196. #define _VAO_NDrW            0x0004    // Add-on needs a draw window.
  197. #define _VAO_NStW            0x0008    // Add-on needs a stencil window.
  198. #define _VAO_NShW            0x0010    // Add-on needs a sheet window.
  199. #define _VAO_NIcW            0x0020    // Add-on needs an icon window.
  200. #define _VAO_NT                0x0040    // Add-on needs a target context.
  201. #define _VAO_NPgT            0x0080    // Add-on needs target that is a page.
  202. #define _VAO_NMsT            0x0100    // Add-on needs target that is a master.
  203. #define _VAO_NS             0x0200    // Add-on needs a selection.
  204.  
  205. #define VAO_NEEDSDOC        _VAO_ND
  206. #define VAO_NEEDSDOCWND     _VAO_ND|_VAO_NW
  207. #define VAO_NEEDSDRAWWND    _VAO_ND|_VAO_NW|_VAO_NDrW
  208. #define VAO_NEEDSPAGEWND    _VAO_ND|_VAO_NW|_VAO_NDrW|_VAO_NPgT
  209. #define VAO_NEEDSMASTERWND    _VAO_ND|_VAO_NW|_VAO_NDrW|_VAO_NMsT
  210. #define VAO_NEEDSSTENWND    _VAO_ND|_VAO_NW|_VAO_NStW
  211. #define VAO_NEEDSSHEETWND    _VAO_ND|_VAO_NW|_VAO_NShW
  212. #define VAO_NEEDSICONWND    _VAO_ND|_VAO_NW|_VAO_NIcW
  213. #define VAO_NEEDSTARGET        _VAO_ND|_VAO_NT
  214. #define VAO_NEEDSTARGPAGE    _VAO_ND|_VAO_NT|_VAO_NPgT
  215. #define VAO_NEEDSTARGMASTER    _VAO_ND|_VAO_NT|_VAO_NMsT
  216. #define VAO_NEEDSSELECTION    _VAO_ND|_VAO_NT|_VAO_NS
  217.  
  218. // VAO_INVOKEMASK: Specifies what events, if any, an Add-on wants to
  219. // be automatically invoked on. Value should be mask of zero or more
  220. // VAO_INVOKExxx values.
  221. //
  222. typedef WORD VAO_INVOKEMASK, FAR* LPVAO_INVOKEMASK;
  223.  
  224. #define VAO_INVOKE_LAUNCH    0x0001    // Invoke on Visio Launch. The vsl file
  225.                                     // must reside in a directory that is
  226.                                     // listed in Visio's startup path list
  227.                                     // for this to have an effect.
  228.  
  229. typedef WORD VAO_NOTIFYMASK, FAR* LPVAO_NOTIFYMASK;
  230.  
  231. // This is the maximum add-on name length we'll allow an add-on name to
  232. // have (not counting the null at its end). Names over 20 or so characters
  233. // will be truncated when made visible by the UI, so names much longer
  234. // than that aren't particularly useful anyway.
  235. //
  236. #define VAOMAXAONAME 100
  237.  
  238. VAO_EMBEDDABLE_STRUCT
  239.     {
  240.     VAO_ORDINAL        ord;            // Ordinal of Add-on. This should be
  241.                                     // a value other than VAO_INV_ORD. Each
  242.                                     // Add-on registered by a given Add-on
  243.                                     // library should be assigned a distinct
  244.                                     // ordinal.
  245.  
  246.     VAO_ATTS        atts;            // Attributes of Add-on.
  247.     VAO_ENABMASK    enabMask;        // Add-on's enabling policy.
  248.     VAO_INVOKEMASK    invokeOnMask;    // 
  249.     VAO_NOTIFYMASK    notifyOnMask;    // 
  250.  
  251.     LPCTSTR            lpName;            // Add-on's name.
  252.                                     //
  253.                                     //    - Visio makes a copy of the name
  254.                                     //      hence the lib needn't keep memory
  255.                                     //      pointed to by lpName around.
  256.                                     //
  257.                                     //    - Name can be null or "", but it
  258.                                     //      won't show up in Run Add-on
  259.                                     //      dialog and analogous dialogs.
  260.                                     //
  261.                                     //    - If the name isn't null, Visio will
  262.                                     //      return an error if a given Add-on
  263.                                     //      lib registers more than one Add-on
  264.                                     //      with the same name.
  265.                                     //
  266.                                     //    - Visio assumes name is an ansi (as
  267.                                     //      opposed to an oem) string. This
  268.                                     //      makes a difference if the name
  269.                                     //      container e.g. accented characters.
  270.     } VAOREGSTRUCT, FAR* LPVAOREGSTRUCT;
  271.  
  272.  
  273. //---------------------------------------------------------------------------
  274. //    MESSAGES THAT CROSS THE VISIO/ADD-ON LIBRARY INTERFACE
  275. //---------------------------------------------------------------------------
  276.  
  277.  
  278. #define _VAOGEN_INVBASE    (0x0000)    // First invariant generic message/rc
  279. #define _VAOGEN_SENBASE    (0x1000)    // First int sensitive generic message/rc
  280.  
  281. #define _V2L_INVBASE    (0x2000)    // First invariant v2l message/rc
  282. #define _V2L_SENBASE    (0x3000)    // First int sensitive v2l message/rc
  283.  
  284. #define _L2V_INVBASE    (0x4000)    // First invariant l2v message/rc
  285. #define _L2V_SENBASE    (0x5000)    // First int sensitive l2v message/rc
  286.  
  287. //---------------------------------------------------------------------------
  288. //
  289. //    MESSAGES THAT CROSS THE VISIO/ADD-ON LIBRARY INTERFACE
  290. //    ------------------------------------------------------
  291. //
  292. //    The "V2L" messages below are messages that Visio passes to an Add-on
  293. //    library. The "L2V" messages are messages a library passes to Visio.
  294. //
  295. //    The receiver of a message should respond by returning a VAORC (Visio
  296. //    Add-on Return Code) to the message sender. The return codes defined as
  297. //    part of this interface are given later in this file.
  298. //
  299. //    Passed with each message are two parameters, a WORD and an LPVOID. In
  300. //    many cases the LPVOID should point to a structure whose type is a function
  301. //    of the message being sent. Definitions of the various message related
  302. //    structures are given later in this file. Depending on the message, fields
  303. //    in a message structure may be set by the sender or the receiver of the
  304. //    message. In all cases the sender of the message is to be construed as
  305. //    the owner of the memory allocated for the message structure.
  306. //
  307. //    Discussion of individual messages can be found later in this file.
  308. //
  309. //---------------------------------------------------------------------------
  310.  
  311. typedef enum
  312.     {
  313.     INVALID_VAOMSG            = _VAOGEN_INVBASE,    // The code no msg can have.
  314.  
  315.     // Messages that Visio sends to a VSL:
  316.     V2LMSG_LOAD                = _V2L_INVBASE,
  317.     V2LMSG_UNLOAD,
  318.     V2LMSG_ENUMADDONS        = _V2L_SENBASE,
  319.     V2LMSG_ISAOENABLED,
  320.     V2LMSG_RUN,
  321.     V2LMSG_RUNABOUT,
  322.     V2LMSG_RUNHELP,
  323.     V2LMSG_KILLSESSION,
  324.     _V2LMSG_FIRSTFREE,
  325.  
  326.     // Messages that a VSL sends to Visio:
  327.     L2VMSG_AVAILCALLS        = _L2V_INVBASE,    // Not for external use.
  328.     L2VMSG_REGADDON            = _L2V_SENBASE,
  329.     L2VMSG_UNREGADDON,
  330.     L2VMSG_ISAOENABLED,
  331.     L2VMSG_ISCMDENABLED,            // Not for external use.
  332.     L2VMSG_ENABLEMENU_obsolete,        // Consume id for backwards compatibility.
  333.     L2VMSG_ISCMDQUERY_obsolete,        // Consume id for backwards compatibility.
  334.     L2VMSG_GETARGSIZE,                // Not for external use.
  335.     L2VMSG_AVAILMODES_obsolete,        // Consume id for backwards compatibility.
  336.     L2VMSG_EXECUTE,                    // Not for external use.
  337.     L2VMSG_ENUMDOCS_obsolete,        // Consume id for backwards compatibility.
  338.     L2VMSG_ENUMCONS_obsolete,        // Consume id for backwards compatibility.
  339.     L2VMSG_ENUMSHEETS_obsolete,        // Consume id for backwards compatibility.
  340.     L2VMSG_SESSIONDONE,
  341.     L2VMSG_PROMPTUSER_obsolete,        // Consume id for backwards compatibility.
  342.     L2VMSG_DBL2ASCII_obsolete,        // Consume id for backwards compatibility.
  343.     L2VMSG_ASCII2DBL_obsolete,        // Consume id for backwards compatibility.
  344.     L2VMSG_GETAPPINFO_obsolete,        // Consume id for backwards compatibility.
  345.     L2VMSG_DEBUGMSG_obsolete,        // Consume id for backwards compatibility.
  346.  
  347.     // --values below here were added to Visio 4.0--
  348.     L2VMSG_BINDDATA,    
  349.     L2VMSG_BOUNDDATA,    
  350.  
  351.     _L2VMSG_FIRSTFREE,
  352.  
  353.     } VAOMSG_ENUM, FAR* LPVAOMSG_ENUM;
  354.  
  355.  
  356. // --------------------
  357. // GENERIC RETURN CODES
  358. // --------------------
  359.  
  360. #define VAORC_SUCCESS            (_VAOGEN_INVBASE+0)
  361.                                             // ASSERT(VAORC_SUCCESS==0);
  362.  
  363. #define VAORC_FAILURE            (_VAOGEN_SENBASE+0)
  364.  
  365. #define VAORC_L2V_LOADFAILED    (_L2V_INVBASE+0)
  366.                                 // Prescribed error response to V2LMSG_LOAD.
  367.  
  368. #define VAORC_L2V_ENABLED        (_L2V_SENBASE+0)
  369.                                 // True response by lib to V2LMSG_ISAOENABLED
  370.                                 // query. (False response should be 0.)
  371.  
  372. #define VAORC_L2V_MODELESS        (_L2V_SENBASE+1)
  373.                                 // Prescribed lib response to V2LMSG_RUNxxx
  374.                                 // meaining session persists.
  375.  
  376. #define VAORC_L2V_GOTNOABOUT    (_L2V_SENBASE+2)
  377.                                 // Prescribed lib response to V2LMSG_RUNABOUT
  378.                                 // meaining lib didn't respond to Visio's
  379.                                 // request. Visio will respond by displaying
  380.                                 // a very generic about box. Note that Visio
  381.                                 // will only send V2LMSG_RUNABOUT to Add-ons
  382.                                 // that declare VAO_AOATTS_HASABOUT in their
  383.                                 // registration structure. So Add-ons that
  384.                                 // really don't provide about should say so
  385.                                 // when registering.
  386.  
  387. #define VAORC_L2V_GOTNOHELP        (_L2V_SENBASE+3)
  388.                                 // Prescribed lib response to V2LMSG_RUNHELP
  389.                                 // meaining lib didn't respond to Visio's
  390.                                 // request. Visio will respond by displaying
  391.                                 // very generic. Note that Visio will only
  392.                                 // send V2LMSG_RUNHELP to Add-ons that
  393.                                 // declare VAO_AOATTS_HASHELP in their
  394.                                 // registration structure. So Add-ons that
  395.                                 // really don't provide help should say so
  396.                                 // when registering.
  397.                                 
  398. #define VAORC_L2V_BADMSG        (_L2V_SENBASE+5)
  399.                                 // Lib returns this if sent illegal message.
  400.  
  401.  
  402. //---------------------------------------------------------------------------
  403. //
  404. //    INDIVIDUAL MESSAGE DESCRIPTIONS:
  405. //    -------------------------------
  406. //
  407. //    Messages sent from Visio to library
  408. //    -----------------------------------
  409. //
  410. //    wmsg                wparam            lparam            return
  411. //    ----                ------            ------            ------
  412.  
  413.  
  414. //    V2LMSG_LOAD            Visio Version    LPVAOFUNC        VAO_L2V_VERSION() |
  415. //                                                        VAORC_L2V_LOADFAILED
  416. //
  417. //
  418. //        Visio sends V2LMSG_LOAD to an Add-on library right after it has
  419. //        done LoadLibrary() and GetProcAddress(LPVAOENTRYNAME) on the library.
  420. //
  421. //        The value of the wparam passed with V2LMSG_LOAD indicates the Add-on
  422. //        interface version being used by the sending Visio. Typically the
  423. //        receiving library shouldn't care. However, if it so chooses, it can
  424. //        refuse to load itself based on the version of Visio it is running
  425. //        with. WParam packs the major and minor interface version numbers
  426. //        being used by Visio in the same fashion as described below for
  427. //        VAO_L2V_VERSION(). [See (*) below.]
  428. //
  429. //        The value of the lparam passed    with V2LMSG_LOAD is a pointer to the
  430. //        procedure in Visio the library is to call when it wants to make calls
  431. //        back into Visio later.
  432. //
  433. //        Visio expects a response of VAO_L2V_VERSION() to V2LMSG_LOAD unless
  434. //        the library fails to initialize itself. If initialization fails, the
  435. //        response should be VAORC_L2V_LOADFAILED, in which case Visio will
  436. //        perform an immediate FreeLibrary() and send the lib no more messages.
  437. //
  438. //        Note: This value should never have _L2V_INVBASE bit set in it!
  439. //        That way we can always distinguish it from VAORC_L2V_LOADFAILED.
  440. //
  441.         #define VAO_L2V_VERSION() ((VAORC)( (VAO_IFMAJOR<<8) | VAO_IFMINOR ))
  442. //
  443. //        Visio disables library call backs when it sends V2LMSG_LOAD.
  444. //
  445. //        Note that a Visio INSTANCE will send V2LMSG_LOAD when it loads an
  446. //        Add-on library. Thus a library may receive V2LMSG_LOAD multiple
  447. //        times without receiving intervening V2LMSG_UNLOADs if multiple Visio
  448. //        instances are running. Thus a library wanting to perform instance
  449. //        independent initialization can take one of several tacks:
  450. //
  451. //        option1:    Do instance independent initialization in its LibMain().
  452. //        option2:    Keep a global load count around that's initialized to 0,
  453. //                    incremented when V2LMSG_LOAD is received and decremented
  454. //                    when V2LMSG_UNLOAD is received. Instance Instance
  455. //                    independent initialization should then occur when
  456. //                    V2LMSG_LOAD is received and the load count is 0. Services
  457. //                    implementing this option are available in vlibutils.h/c.
  458. //
  459. //        (*): Visio 2.0, which implemented version 2.1 of the Add-on interface,
  460. //        passed wparam as VAO_INV_SESSID. Versions of Visio that implement
  461. //        version 2.2 or later of the Add-on interface pass the interface
  462. //        version they are using in wparam as described above.
  463. //
  464.         #define _21VISIO VAO_INV_SESSID
  465.  
  466.  
  467. //    V2LMSG_UNLOAD        undefined        NULL            moot
  468. //
  469. //        Visio sends V2LMSG_UNLOAD to an Add-on library right before it is
  470. //        about to do a FreeLibrary() on the library (probably because it is
  471. //        quitting). The library has no choice in this matter, V2LMSG_UNLOAD
  472. //        doesn't allow the library to respond that it doesn't want to be
  473. //        unloaded. The result a library returns in response to V2LMSG_UNLOAD
  474. //        is really moot (but VAORC_SUCCESS is suggested).
  475. //
  476. //        Note that Visio doing a FreeLibrary() doesn't necessarily imply the
  477. //        library is really about to be unloaded. Windows will decrement the
  478. //        library's use count when Visio does the FreeLibrary() and actually
  479. //        unload the library only if the use count decrements to zero. The use
  480. //        count may still be non-zero if multiple instances of Visio have loaded
  481. //        the library. If the library has instance independent cleanup that it
  482. //        only wants to perform when it is really going to be unloaded, it can
  483. //        put the cleanup in its WEP() procedure or maintain a use count as
  484. //        described above in the V2LMSG_LOAD discussion.
  485. //
  486. //        Visio disables library call backs when it sends V2LMSG_UNLOAD.
  487. //
  488. //        Note that Visio will never send V2LMSG_UNLOAD to a library that has
  489. //        modeless sessions in progress (see V2LMSG_RUN). Rather, it will send
  490. //        V2LMSG_KILLSESSIONs until no sessions remain, then send V2LMSG_UNLOAD.
  491.  
  492.  
  493. //    V2LMSG_ENUMADDONS    0                LPVAOV2LSTRUCT    VAORC
  494. //
  495. //        Visio sends V2LMSG_ENUMADDONS to a library when it is requesting
  496. //        the library to enumerate its Add-ons. Typically a library will respond
  497. //        by sending L2VMSG_REGADDON messages back to Visio.
  498. //
  499. //        The VAOV2LSTRUCT pointed to by lparam specifies information the
  500. //        library will need in order to make calls back into Visio.
  501. //
  502. //        If the result returned by the library in response to V2LMSG_ENUMADDONS
  503. //        isn't VAORC_SUCCESS, Visio will send an immediate V2LMSG_UNLOAD and
  504. //        not deal further with the library. If some but not all of a library's
  505. //        Add-ons register successfully and if the library wishes to continue,
  506. //        it should respond VAORC_SUCCESS to V2LMSG_ENUMADDONS.
  507.  
  508.  
  509. //    V2LMSG_ISAOENABLED    i                LPVAOV2LSTRUCT    VAORC_L2V_ENABLED | 0
  510. //
  511. //        Visio sends V2LMSG_ISAOENABLED to a library when it is requesting
  512. //        the library to indicate whether the Add-on whose ordinal is passed
  513. //        in wparam is enabled or not. Visio will only send this message if
  514. //        the targeted Add-on was registered as having an enabling policy of
  515. //        VAO_ENABLEDYNAMIC or VAO_ENABLEDYNAMICEX. In the latter case message
  516. //        will only be sent if static tests indicate Add-on potentially enabled.
  517. //
  518. //        The library should respond VAORC_L2V_ENABLED or 0.
  519. //
  520. //        The VAOV2LSTRUCT pointed to by lparam specifies information the
  521. //        library will need in order to make calls back into Visio.
  522.  
  523.  
  524. //    V2LMSG_RUN            i                LPVAOV2LSTRUCT    VAORC_SUCCESS |
  525. //                                                        VAORC_L2V_MODELESS |
  526. //                                                        VAORC_SomeError
  527. //
  528. //        Visio sends V2LMSG_RUN to a library when it is requesting the library
  529. //        to run the Add-on whose ordinal is passed in wparam. Visio will only
  530. //        send this message if the targeted Add-on has been deemed currently
  531. //        enabled according to the enabling policy declared for it when it was
  532. //        registered.
  533. //
  534. //        The VAOV2LSTRUCT pointed to by lparam specifies information the
  535. //        library will need in order to make calls back into Visio.
  536. //
  537. //        If the invoked Add-on completes whatever operation it performs in
  538. //        response to V2LMSG_RUN, then VAORC_SUCCESS or VAORC_SomeError should
  539. //        be returned by the library to Visio in response to the message.
  540. //
  541. //        If the Add-on initiated some modeless activity in response to the
  542. //        V2LMSG_RUN (e.g. opened a window), then VAORC_L2V_MODELESS should
  543. //        be returned in response to the message. Such a modeless session will
  544. //        persist until the library sends L2VMSG_SESSIONDONE to Visio, or until
  545. //        Visio sends V2LMSG_KILLSESSION to the library. Visio won't send
  546. //        V2LMSG_UNLOAD to a library that has modeless sessions in progress.
  547.  
  548.  
  549. //    V2LMSG_RUNABOUT        i                LPVAOV2LSTRUCT    VAORC_SUCCESS |
  550. //                                                        VAORC_L2V_MODELESS |
  551. //                                                        VAORC_SomeError
  552. //
  553. //        Visio sends V2LMSG_RUNABOUT to a library when it is requesting the
  554. //        library to invoke "about" for the the Add-on whose ordinal is passed
  555. //        in wparam. Visio will only send this message if the targeted Add-on
  556. //        was declared to provide "about" when it was registered.
  557. //
  558. //        The VAOV2LSTRUCT pointed to by lparam specifies information the
  559. //        library will need in order to make calls back into Visio.
  560. //
  561. //        The result Visio expects a library to return in response to
  562. //        V2LMSG_RUNABOUT is exactly as described for V2LMSG_RUN.
  563.  
  564.  
  565. //    V2LMSG_RUNHELP        i                LPVAOV2LSTRUCT    VAORC_SUCCESS |
  566. //                                                        VAORC_L2V_MODELESS |
  567. //                                                        VAORC_SomeError
  568. //
  569. //        Visio sends V2LMSG_RUNHELP to a library when it is requesting the
  570. //        library to invoke help for the the Add-on whose ordinal is passed
  571. //        in wparam. Visio will only send this message if the targeted Add-on
  572. //        was declared to provide help when it was registered.
  573. //
  574. //        The VAOV2LSTRUCT pointed to by lparam specifies information the
  575. //        library will need in order to make calls back into Visio.
  576. //
  577. //        The result Visio expects a library to return in response to
  578. //        V2LMSG_RUNHELP is exactly as described for V2LMSG_RUN.
  579.  
  580.  
  581. //    V2LMSG_KILLSESSION    0                LPVAOV2LSTRUCT    VAORC (ignored)
  582. //
  583. //        Visio sends V2LMSG_KILLSESSION to a library when it is mandating that
  584. //        a session that an in progress session be terminated. The library can't
  585. //        refuse this request.
  586. //
  587. //        The session to be terminated is identified in the VAOV2LSTRUCT
  588. //        pointed to by lparam.
  589. //
  590. //        When it sends V2LMSG_KILLSESSION, the only call backs Visio enables
  591. //        are the so called "shutdown" call backs.
  592. //
  593. //        Typically this message will be sent to a session that previously
  594. //        "went modeless." See V2LMSG_RUN description above. However, in rare
  595. //        cases it may also be sent to an uncompleted modal session, e.g.
  596. //        session invokes app modal dialog, user switches to program manager,
  597. //        then exits Windows.
  598.  
  599.  
  600. //    Messages sent from library to Visio
  601. //    -----------------------------------
  602. //
  603. //    When an Add-on library sends a message to Visio (really meaning it makes
  604. //    a call back into Visio), it must always pass as wparam the id associated
  605. //    with the session doing the calling. This id is passed by Visio to the
  606. //    library in the LPVAOV2LSTRUCT passed as lparam on most messages sent
  607. //    from Visio to an Add-on library, specifically in lpvaov2lstruct->wSessID.
  608. //    The address of the procedure in Visio the library is to call is passed
  609. //    in lpvaov2lstruct->lpfunc.
  610. //
  611. //    ---WIN16 ONLY---
  612. //    Note that several instances of Visio may be running at once. Although
  613. //    chances are small that it will happen, there is no guarantee that
  614. //    distinct instances won't invoke a session with the same id. Thus a
  615. //    session is really keyed by (hVisInst,wSessID), both of which are passed
  616. //    with the VAOV2LSTRUCTs passed to the lib when Visio starts a session.
  617. //    When you pass wSessID back to Visio you're implicitly identifying the
  618. //    session with id wSessID that belongs to the currently running Visio
  619. //    instance. Keep this in mind if your lib keeps session specific data
  620. //    structures. 
  621. //
  622. //    ---WIN32 ONLY---
  623. //    Above discussion is slightly different in win32. In the event that
  624. //    several Visio's are running, many "instances" of a library are loaded,
  625. //    unlike the win16 case where one instance gets loaded that is driven by
  626. //    the many Visio instances. Thus a win32 library always thinks it is 
  627. //    running with a lone instance of Visio. This typically makes things 
  628. //    easier for a win32 library that wants to maintain session specific data
  629. //    structures. It needn't take app instance into account as a component of
  630. //    the key. 
  631. //
  632. //    wmsg                wparam            lparam            return
  633. //    ----                ------            ------            ------
  634.  
  635. //    L2VMSG_REGADDON        wSessID         LPVAOREGSTRUCT    VAORC
  636. //
  637. //        L2VMSG_REGADDON tells Visio to register an Add-on implemented by
  638. //        an Add-on library. The Add-on is described by the VAOREGSTRUCT
  639. //        pointed to by lparam. The library should fill out the VAOREGSTRUCT
  640. //        prior to sending L2VMSG_REGADDON.
  641. //
  642. //        Typically a library sends L2VMSG_REGADDON in response to receiving
  643. //        V2LMSG_ENUMADDONS from Visio. However, V2LMSG_ENUMADDONS can be sent
  644. //        at other times if a library finds occasion for doing so.
  645.  
  646.  
  647. //    L2VMSG_UNREGADDON    wSessID         LPVAOREGSTRUCT    VAORC
  648. //
  649. //        L2VMSG_UNREGADDON tells Visio to unregister an Add-on that was
  650. //        previously registered. The VAOREGSTRUCT pointed to by lparam says
  651. //        which Add-on to unregister. Only the ordinal of the Add-on needs to
  652. //        be specified in the VAOREGSTRUCT.
  653.  
  654.  
  655. //    L2VMSG_ISAOENABLED    wSessID         LPVAOREGSTRUCT    VAORC_V2L_ENABLED | 0
  656. //
  657. //        L2VMSG_ISAOENABLED passes a VAOREGSTRUCT in which an Add-on enabling
  658. //        policy is specified to Visio and Visio returns whether the policy
  659. //        evaluates at the moment to enabled or disabled. The VAOREGSTRUCT may
  660. //        be the registration structure for an actual Add-on, but that need
  661. //        not be the case. Only the enabling policy field of the VAOREGSTRUCT
  662. //        needs to be filled out. Visio ignores the other VAOREGSTRUCT fields.
  663. //        If the specified policy is VAO_ENABLEDYNAMIC (i.e. the library
  664. //        evaluates the enabledness of an add-on) then Visio will return 0,
  665. //        otherwise it will use the same logic it uses to determine whether
  666. //        a statically enabled Add-on with the specified enabling policy is
  667. //        enabled or not. Visio returns VAORC_V2L_ENABLED or 0.
  668.  
  669.  
  670. //    L2VMSG_SESSIONDONE    wSessID         NULL            VAORC
  671. //
  672. //        A library sends L2VMSG_SESSIONDONE to Visio when it wants to end
  673. //        on its own volition a session that previously "went modeless" (see
  674. //        V2LMSG_RUN description).
  675. //
  676. //        L2VMSG_SESSIONDONE might be used e.g. if the library opened a window
  677. //        in response to V2LMSG_RUN. When the user closes the window, the
  678. //        library would send L2VMSG_SESSIONDONE to Visio. Note that if Visio
  679. //        wants a library to end a modeless session, e.g. when it's quitting,
  680. //        then it will send V2LMSG_KILLSESSION to the library. A library can
  681. //        respond to V2LMSG_KILLSESSION by sending L2VMSG_SESSIONDONE, but it
  682. //        need not do so.
  683.  
  684.  
  685. //    L2VMSG_BINDDATA        wSessID         LPVOID            VAORC
  686. //
  687. //        A library sends L2VMSG_BINDDATA to Visio when it wants to associate
  688. //        an arbitrary pointer with a session. The pointer can be retrieved 
  689. //        later using L2VMSG_BOUNDDATA.
  690.  
  691.  
  692. //    L2VMSG_BOUNDDATA    wSessID         LPVOID FAR*        VAORC
  693. //
  694. //        A library sends L2VMSG_BOUNDDATA to Visio to retrieve the pointer 
  695. //        that was most recently bound to the session via L2VMSG_BINDDATA.
  696. //        Null is returned if L2VMSG_BINDDATA has never been invoked on 
  697. //        the session.
  698.  
  699.  
  700.  
  701. // The implementations for the following few methods can be found in vao.c.
  702. // VAOUtil_DefVisMainProc() provides default handling for a message sent from
  703. // Visio to a VSL's VisioLibMain proc. You can see an example of its use in
  704. // lib.c. VAOUtil_SetVisCallBack() need only be called if you decide not to 
  705. // let VAOUtil_DefVisMainProc() handle the V2LMSG_LOAD message from Visio. 
  706. // VAOUtil_VisCallBack() provides the address of the proc in Visio that a VSL
  707. // is to call in order to send messages to. You'll probably find little reason
  708. // to use it. VAOUtil_RegisterAddons() is used by a VSL to register its Add-ons
  709. // with Visio. See lib.c for an example of its use. VAOUtil_SendEndSession() is 
  710. // to be called by a "modeless" session when it wants to end itself. 
  711. //
  712. VAOU_PROC(VAORC) VAOUtil_DefVisMainProc ( VAOMSG    wMsg,
  713.                                             WORD        wParam,
  714.                                             LPVOID    lpParam,
  715.                                             HINSTANCE    hResources );
  716.  
  717.  
  718. VAOU_PROC(VOID)    VAOUtil_SetVisCallBack    ( LPVAOFUNC lpfunc );
  719.  
  720.  
  721. VAOU_PROC(LPVAOFUNC) VAOUtil_VisCallBack ( void );
  722.  
  723.  
  724. #if !defined(_WIN32)
  725. VAOU_PROC(HINSTANCE) VAOUtil_hAppInst ( void );
  726. #endif
  727.  
  728.  
  729. VAOU_PROC(VAORC) VAOUtil_RegisterAddons ( WORD             wSessID,
  730.                                             LPVAOREGSTRUCT lpRegStructArray,
  731.                                             WORD             nRegStructs );
  732.  
  733. #define VAOUtil_SendEndSession(wSessID)                                     \
  734.             ((*((LPVAOFUNC)(VAOUtil_VisCallBack())))                        \
  735.                                         (L2VMSG_SESSIONDONE,                \
  736.                                           (wSessID),                            \
  737.                                           (LPVOID)NULL))
  738.  
  739. // gbl_hDLLModule is the instance handle for the dll this code is running
  740. // in. It gets set by LibMain() or DllMain() when this dll gets loaded. 
  741. //
  742. extern HINSTANCE gbl_hDLLModule;
  743.  
  744. #define VLIBUTL_hModule() gbl_hDLLModule
  745.  
  746. #if !defined(RC_INVOKED)
  747.     // Resume to using default struct packing.
  748.     #pragma pack()
  749. #endif
  750.  
  751. #define VAOEXPORT __declspec(dllexport)
  752.  
  753. #ifdef __BORLANDC__
  754. #define UNUSED_ARG(x) if (x) { }
  755. #else
  756. #define UNUSED_ARG(x)
  757. #endif
  758.  
  759. #if defined(__cplusplus)
  760.     }    /* End of extern "C" { */
  761. #endif
  762.  
  763. #endif /* _VAO_H */
  764.